A listbox is a rectangular control that contains a list of items. If there are more items than can be viewed, the scrollbar is activated automatically so that the user can view the entire list.

The command to create a listbox looks like this:

LISTBOX #handle.ext, array$(), eventHandler, leftX, topY, width, height

The window handle is required, followed by a unique extension for this listbox control. The array associated with the listbox is names, as is the event handler for the listbox, and its left X position, upper Y position, and width and height. Program execution jumps to the listbox eventHandler when the user doubleclicks on an item in the list.

Array$

The array associated with the listbox must be filled before the listbox is opened. It must be a single-dimensioned string array. If at any time, the contents of the array change, you can issue a "RELOAD" command to the listbox to cause its list to be updated with the current contents of the array.

print #handle.ext, "reload"

By Index

Items can be accessed an retrieved by their index numbers in the listbox. The index number of an item in the listbox does not necessarily match its index number in the array! Listbox index numbers start at 1, so if your array begins with element 0, it will become element 1 in the listbox. Listboxes do not add empty items, so any empty slots in the array are not added as listbox elements. To cause a listbox to appear with an item highlighted, use the "selectindex" command. If the index number is hard coded, it is placed inside the quotation marks. If it is a variable, it is placed outside the quotation marks.

print #handle.ext, "selectindex 1"
print #handle.ext, "selectindex "; i

At any time, you can discover which item in a listbox is selected with the "selectionindex?" command. The name following the command inside of the quotation marks is a variable that will contain the index number selected.

print #handle.ext, "selectionindex? index"
notice "You selected the item whose index is ";index

By String

You can also access or retrieve listbox items by their string value. To cause an item whose string is "string", you issue the "select" command. If the string is a literal string value, it is placed within the quotation marks. If it is a string variable, it is placed outside the quotation marks.

print #handle.ext, "select string"
print #handle.ext, "select "; string$

At any time, you can discover the string that is selected in the listbox with the "selection?" command. The string selected will be placed into the string variable whose name follows the command. This string variable name must be placed inside the quotation marks.

print #handle.ext, "selection? selected$"
notice "You selected this item: ";selected$

SINGLECLICKSELECT

By default, a user must doubleclick to select an item in the listbox. You can change this behavior so that the event handler is triggered when the user singleclicks an item with the "singleclickselect" command:

print #handle.ext, "singleclickselect"

Giving Keyboard Input Focus to the Listbox

You can issue a "setfocus" command to the listbox. This means that any keypresses will be directed to the listbox. When the listbox has the input focus, the user does not need to click with the mouse in the listbox first. The user can scroll with the arrow keys to make a selection.

print #handle.ext, "setfocus"

Relocating, Disabling, Hiding the Listbox

A listbox in a window of type "window" can be relocated during program execution with the "locate" command. This command must be followed by a "refresh" command given to the window to cause the window to be redrawn to show the new location.

print #handle.ext, "locate x y width height"
print #handle, "refresh"

You can also hide the listbox, then show it again at a later time with the "hide" and "show" commands:

print #handle.ext, "show"
print #handle.ext, "hide"

By default, the listbox is enabled and can be accessed by the user. You can disable the listbox so that it can be viewed by the user, but no selection can be made. The appearance of a disabled listbox is slightly different. It appears to be "grayed out." You can enable or disable the listbox at any time during program execution with the "enable" and "disable" commands.

print #handle.ext, "enable"
print #handle.ext, "disable"

Customizing the Appearance of a Listbox with Colors and Fonts

If the variable "ListboxColor$" is filled before the command to create the listbox, the listbox appears in the specified color.

ListboxColor$="cyan"

It isn't possible to change the font color in an individual listbox control, but you can change the font color displayed on all controls in a window by setting the ForegroundColor$ variable.

ListboxColor$="darkred"
ForegroundColor$="white"

The font can be changed as well. You can select a facename, size, and various attributes. See the helpfile topic on specifying fonts for the details. The "font" command follows this syntax:

print #handle.ext, "font facename pointSize"

Here is an actual command:

print #handle.ext, "font times_new_roman 10 italic"

You can remove the automatic scrollbar using the stylebits command. This must be done before opening the window and the scrollbar cannot be shown again at runtime.

Here is the same program that was used in the examples above, but the listbox scrollbar has been REMOVED:

stylebits #status.list, 0, _WS_VSCROLL, 0, 0

---

API Listbox Commands for Experienced Programmers

You can manipulate scrollbars in graphics windows or graphicboxes with native Liberty BASIC Commands. These scrollbar commands do not work on listboxes. You can show or hide the scrollbar at runtime in a listbox with the ShowScrollBar API call. The scrollbar is not removed, as it is in the Stylebits example above, so it can be removed, then shown again later.

    hList=hwnd(#handle.ext)   'get handle of listbox
    CallDLL #user32, "ShowScrollBar", _
        hList as ulong, _   'handle of listbox
        _SB_VERT as long, _ 'vertical scrollbar
        0 as long, _        '0 hides the bar, 1 shows it
        result as long

Here is the same program that was used in the examples above, but the listbox scrollbar has been HIDDEN:

You can change the text color of an individual listbox by subclassing it and capturing the listbox message with Brent Thorn's wmliberty.dll, which is included with this newsletter. You can also change the listbox so that it displays graphics, multiple colors, etc. with an "owner drawn" listbox. Here are two demos provided by Brent.

---